libremanage
============

libremanage is a simple solution for out-of-band remote management with free
software. libremanage enables a sysadmin to remotely access a server's serial
console and power state, regardless of the state of the main CPU, useful for
resolving early boot issues. It serves an analogous role to IPMI or AMT.

You may also be interested in [OpenBMC](https://github.com/openbmc/openbmc),
another free software project capable of remote management.

Setup
------

Some setup is needed on the host (the sysadmin's computer), the board (the
single-board computer connected to the server), and the managed server itself.

### Setup (host)

Clone this repository and add the resulting `libremanage` directory to your
path. Place your fleet configuration in `$HOME/.libremanage.json`, e.g.
`/home/admin/.libremanage.json`.

The configuration file is JSON, consisting of `servers` and `managers`.
`servers` correspond to physical servers to be managed, such as KGPE-D16s.
`managers` correspond to the intermediate single-board computer, such as the
Beaglebone Blacks. A physical link between a server and its manager is
described by the `manager` entry of the server descriptor.

Each server has its serial port described by the self-explanatory `tty` object. 

Power management is described in the `power` object. `type` refers to the power
management scheme; currently, the only supported option is `hidusb-relay-cmd`,
corresponding to the accordingly named USB HID relay driver. For this driver,
`relay` and `channel` correspond to the relay identifier and the channel number
of the corresponding relay. See `hidusb-relay-cmd` documentation for more
details.

Each manager object lists SSH credentials to access the board: `host`, `port`,
and `username`. These fields are self-explanatory. Password authentication is
not supported; use public-key based login.

### Setup (board)

Any standard GNU/Linux distribution or other `*nix* system should work.
Minimally, the system needs to run an ssh daemon for remote access.

### Setup (server)

Connecting the serial cable to the "manager" board.

Wire the power switch pins to a manager relay.

Usage
------

Type `libremanage` for detailed information.

Why?
-----

With OpenBMC, each server board supporting BMC must be ported individually, a
massive task involving reverse-engineering and nontrivial changes across the
stack. Consider that the KGPE-D16 OpenBMC port is estimated to cost upwards of
$60,000. As such, free software conscious users are de facto locked in to
particular server boards, a net negative for freedom in the long-term.

Further, OpenBMC is incredibly complex. While this may be appropriate for
advanced use-cases, it is overkill for the simple remote management tasks
required in practice (serial and power access). The KGPE-D16 server port, for
instance, takes several hours to compile on-board, and binary images are not
supplied due to hard-coded passwords. OpenBMC is an embedded GNU/Linux
distribution in and of itself, intimately connected with complex parts of the
desktop GNU/Linux stack like `dbus` and `systemd`; its functionality is exposed
over an embedded web server. The interface, requiring an isolated network due
to a lack of SSL support, is even planned to be implemented in a
JavaScript-heavy HTML5 "webapp".

Whereas OpenBMC takes a maximalist approach, libremanage takes a minimalist
approach. Its feature set is comparatively tiny, but it requires almost no
specific `libremanage` code. The vast majority of its functionality is handled
by standard, implementation-agnostic *nix tools, a win for maintainability. The
drawback is an increase in physical complexity; while OpenBMC runs on a chip
embedded in the board itself, libremanage requires a dedicated, external
single-board computer with serial cables and relays. Still, in light of the
above issues, this is a net win.
